<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<title>Using A Binary Sensor Mask Example (k-Wave)</title>
	<link rel="stylesheet" href="kwavehelpstyle.css" type="text/css">
	<meta name="description" content="Using A Binary Sensor Mask Example.">
</head>

<body><div class="content">

<h1>Using A Binary Sensor Mask Example</h1>

<p>This example demonstrates how to use a binary sensor mask for the detection of the pressure field generated by an initial pressure distribution within a two-dimensional homogeneous propagation medium. It builds on the <a href="example_ivp_homogeneous_medium.html">Homogeneous Propagation Medium Example</a>.</p>

<p>
    <ul>
        <li><a href="matlab:edit([getkWavePath('examples') 'example_ivp_binary_sensor_mask.m']);" target="_top">Open the file in the MATLAB Editor</a></li>
        <li><a href="matlab:run([getkWavePath('examples') 'example_ivp_binary_sensor_mask']);" target="_top">Run the file in MATLAB</a></li>
    </ul>
</p>

<h2>Contents</h2>
<div>
	<ul>
		<li><a href="#heading2">Defining a binary sensor mask</a></li>
		<li><a href="#heading3">Running the simulation</a></li>
	</ul>
</div>

<a name="heading2"></a>
<h2>Defining a binary sensor mask</h2>

<p>In the <a href="example_ivp_homogeneous_medium.html">Homogeneous Propagation Medium Example</a>, the sensor mask (which defines where the pressure field is recorded at each time-step) is defined as a 2 x N matrix of Cartesian points. It is also possible to define the sensor mask as binary matrix (i.e., a matrix of 1's and 0's) representing the grid points within the computational domain that will collect the data. In this case, the sensor mask must have the same dimensions as the computational grid (i.e., it must have <code>Nx</code> rows and <code>Ny</code> columns). Here <code><a href="makeCircle.html">makeCircle</a></code> is used (instead of <code><a href="makeCartCircle.html">makeCartCircle</a></code>) to define a binary sensor mask of an arc created using the midpoint circle algorithm. It is also possible to explicitly create an arbitrary binary sensor mask, or to load one from an external image map (see the <a href="example_ivp_loading_external_image.html">Loading External Image maps Example</a>).</p>

<pre class="codeinput">
<span class="comment">% define a binary sensor mask</span>
sensor_x_pos = Nx/2;        <span class="comment">% [grid points]</span>
sensor_y_pos = Ny/2;        <span class="comment">% [grid points]</span>
sensor_radius = Nx/2 - 22;  <span class="comment">% [grid points]</span>
sensor_arc_angle = 3*pi/2;  <span class="comment">% [radians]</span>
sensor.mask = makeCircle(Nx, Ny, sensor_x_pos, sensor_y_pos, sensor_radius, sensor_arc_angle);
</pre>

<p>A plot of the initial pressure distribution and the sensor mask is given below.</p>

<img vspace="5" hspace="5" src="images/example_ivp_binary_sensor_mask_01.png" style="width:560px;height:420px;" alt="">
    
<a name="heading3"></a>
<h2>Running the simulation</h2>

<p>The computation is again started by calling <code><a href="kspaceFirstOrder2D.html">kspaceFirstOrder2D</a></code>. For a Cartesian sensor mask (as in the <a href="example_ivp_homogeneous_medium.html">Homogeneous Propagation Medium Example</a>), the returned time-series are ordered the same way as the set of Cartesian sensor points. For a binary sensor mask (as in this example), the time-series are instead returned using MATLAB's standard column-wise linear matrix index ordering. As an example, if the sensor mask is defined as</p>

<pre class="codeinput">
0     1     0
1     0     1
1     0     1
0     1     0
</pre>

<p>the ordering of the recorded time series will be</p>

<pre class="codeinput">
0     3     0
1     0     5
2     0     6
0     4     0
</pre>

<p>For both Cartesian and binary sensor masks, the data is indexed as <code>sensor_data(sensor_point_index, time_index)</code>. A visualisation of the recorded time data is given below. The data ordering is clearly visible; the data is returned column-wise from top to bottom, and left to right.<p>

<img vspace="5" hspace="5" src="images/example_ivp_binary_sensor_mask_02.png" style="width:560px;height:420px;" alt="">
        
<p>For 2D simulations, it is possible to reorder the sensor data returned by a binary sensor mask based on the angle that each sensor point makes with the grid origin using <code><a href="reorderSensorData.html">reorderSensorData</a></code>. The angles are defined from the upper left quadrant or negative y-axis in the same way as within <code><a href="makeCircle.html">makeCircle</a></code> and <code><a href="makeCartCircle.html">makeCartCircle</a></code>.</p>

<pre class="codeinput">
<span class="comment">% reorder the simulation data</span>
sensor_data_reordered = reorderSensorData(kgrid, sensor, sensor_data);
</pre>

<img vspace="5" hspace="5" src="images/example_ivp_binary_sensor_mask_03.png" style="width:560px;height:420px;" alt="">

<p>The recorded data at a particular time step can also be restored to its original position in the grid using <code><a href="unmaskSensorData.html">unmaskSensorData</a></code>.</p>

</div></body></html>